/*
 * Copyright (c) 2025 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import { TypeNode } from 'ts-morph';
import { PropertyKind, SerializerMetadata, TypeStructure } from '..';

/**
 * 类型处理器接口
 * 包含类型从识别到代码生成的完整生命周期
 *
 * 设计原则：
 * - 一个Handler只处理一个PropertyKind
 * - Handler包含完整生命周期：识别→解析→配置→生成→验证
 */
export interface ITypeHandler {
  /** 处理器名称（用于日志和调试） */
  readonly name: string;

  /** 处理的类型种类（一个Handler只处理一个Kind） */
  readonly kind: PropertyKind;

  /** 优先级（用于类型匹配冲突解决，数值越大优先级越高） */
  readonly priority: number;

  /**
   * 判断是否能处理当前类型
   * @param typeNode AST节点
   * @param context 上下文
   */
  matches(typeNode: TypeNode, context: TypeContext): boolean;

  /**
   * 解析类型节点为类型结构
   * @param typeNode AST节点
   * @param context 上下文
   */
  parse(typeNode: TypeNode, context: TypeContext): TypeStructure;

  /**
   * 获取序列化器元数据
   * @param structure 类型结构（parse阶段的输出）
   * @param withParam 是否有with参数
   */
  getSerializerMetadata(structure: TypeStructure, withParam?: string): SerializerMetadata;

  /**
   * 生成序列化器实例化代码
   * @param structure 类型结构
   */
  generateInstantiation(structure: TypeStructure): string;

  /**
   * 生成类型声明
   * @param structure 类型结构
   */
  generateTypeDeclaration(structure: TypeStructure): string;

  /**
   * 生成类型键表达式（用于with序列化器）
   * @param structure 类型结构
   */
  generateTypeKey(structure: TypeStructure): string;

  // ==================== Sendable转换相关 ====================

  /**
   * 生成Sendable类型声明
   * 将普通类型转换为Sendable兼容的类型声明
   *
   * @param structure 类型结构
   * @returns Sendable类型声明字符串
   *
   * @example
   * // 基础类型：string -> string
   * // 数组：Array<User> -> collections.Array<SendableUser>
   * // 自定义类：User -> SendableUser（如果启用了generateSendable）
   */
  generateSendableTypeDeclaration(structure: TypeStructure): string;

  /**
   * 生成属性转换代码
   * 用于生成toSendable/toOrigin方法中的属性转换逻辑
   *
   * @param structure 类型结构
   * @param sourceValue 源值表达式（如"this.name"）
   * @param direction 转换方向
   * @returns 转换后的代码表达式
   *
   * @example
   * // 数组转换（toSendable）：
   * //   sourceValue="this.users" -> "new collections.Array(...this.users)"
   * // 数组转换（toOrigin）：
   * //   sourceValue="this.users" -> "new Array(...this.users)"
   * // 基础类型：
   * //   sourceValue="this.name" -> "this.name"（直接传递）
   */
  generatePropertyConversion(structure: TypeStructure, sourceValue: string, direction: ConversionDirection): string;
}

/**
 * 类型上下文
 * 贯穿整个处理流程
 */
export interface TypeContext {
  /** 当前泛型参数 */
  genericParams: string[];

  /** 递归深度 */
  depth: number;
}

/**
 * 转换方向枚举
 */
export enum ConversionDirection {
  /** 普通类型 -> Sendable类型 (toSendable) */
  TO_SENDABLE = 'TO_SENDABLE',

  /** Sendable类型 -> 普通类型 (toOrigin) */
  TO_ORIGIN = 'TO_ORIGIN'
}
